# Pepvoid Rescue & Maintenance

The `rescue-sysadmin` preset builds a focused XFCE Live environment. The edition
adds its own searchable Rescue & Maintenance Center, offline workflow notes and
recovery utilities without changing the regular desktop profiles.

Firefox is included for online documentation, troubleshooting searches and
support. Offline recovery guidance remains available without a connection.

Build with a separate output name so the normal XFCE image is not overwritten:

```sh
sudo python3 cli.py x86_64 --preset rescue-sysadmin --mode real --output pepvoid-rescue-x86_64.iso
```

The center opens at login instead of the generic Welcome. It remains available
in the applications menu, and its startup preference is saved per user. All
new interface text and documentation are English.

The **Recovery guide** button opens the full offline handbook, installed as
`/usr/share/pepvoid-rescue/guide.txt`. Its 31 sections include device identification,
disk and partition cloning/restoration, filesystem checks, file recovery,
encryption, RAID/LVM, boot repair, remote access and troubleshooting. Examples
distinguish inspection from writes and destructive restores, with deliberately
nonexistent device placeholders. Read it in a searchable terminal pager with:

```sh
less /usr/share/pepvoid-rescue/guide.txt
```

## Included workflows

| Area | Tools and behavior |
| --- | --- |
| Storage inventory | lsblk, findmnt, blkid, GParted, Disks, fdisk, parted, sgdisk |
| Drive health | SMART, GSmartControl, NVMe CLI, hdparm, sdparm, SCSI utilities |
| File recovery | TestDisk, PhotoRec, GNU ddrescue with mapfiles, Sleuth Kit |
| Imaging and backups | FSArchiver, Partclone, rsync, archive and checksum tools |
| Filesystems | ext2/3/4, FAT, exFAT, NTFS, XFS, Btrfs, F2FS and Bcachefs utilities |
| Encryption and volume layers | Cryptsetup/LUKS, Dislocker/BitLocker, LVM, mdadm, dmraid |
| Installed-system repair | chroot workspace, GRUB, EFI tools, dracut, offline Windows registry tools |
| Hardware | lshw, inxi, dmidecode, PCI/USB enumeration, sensors, memtester, stress-ng |
| Networking | NetworkManager, SSH, SMB/NFS/SSHFS clients, Nmap, tcpdump, Wireshark, iperf3, dig, socat |
| Reports | Bounded diagnostic commands saved to a private text file chosen by the user |

The graphical checker uses no-repair options for recognized unmounted ext,
XFS, Btrfs, FAT, exFAT and NTFS volumes. It rejects mounted targets/children,
unknown paths and regular files. NTFS inspection is not equivalent to Windows
chkdsk. SMART reads require an explicitly selected device.

**Workspace** entries show task-specific instructions and open an ordinary
shell. They do not execute example commands. Interactive tools such as TestDisk
and PhotoRec are launched directly in their own terminal. No scan, repair,
format, clone, restore or stress test starts automatically at login.

## Focused package selection

The preset omits the full development profile (Rust, Go, Node.js and compiler
collections), printing applications, Flatpak, Vulkan and video-acceleration
packages. It replaces XFCE metapackages with the components used by the existing
desktop/panel. Necessary dependencies are still resolved by XBPS; an exclusion
from the request list is not a package-manager dependency blacklist.

Firmware, graphics needed for the desktop, network access, accessibility,
audio and tools useful for viewing recovered data remain available. SSH is
installed but disabled at boot. Thunar removable-media automount and autorun
are disabled only in this edition. Clicking a volume can still mount it.

## Recovery boundaries

This edition provides tools, not a universal automatic repair procedure. A
failing disk should normally be imaged to healthy storage before filesystem
repair. Recovery destinations must not reside on the source disk. Filesystem
journal replay, encrypted layers and RAID/LVM activation require appropriate
options and informed device selection. Kernel/initramfs discovery may activate
storage; the edition is not a forensic write blocker.

BitLocker requires valid keys and supported encryption features. Linux boot
repair uses the installed distribution's tooling and actual partition layout.
Windows boot/filesystem repair may require Microsoft recovery media. ZFS,
proprietary RAID and unsupported filesystem/encryption variants may require
additional matching modules or vendor tools. Memtest86+ is provided for x86;
its availability depends on the firmware/boot environment.

Reports may include disk serials, UUIDs and network identifiers. They are saved
with mode 0600, never overwrite existing files/symlinks and record unavailable
commands or timeouts. Save them to persistent storage before rebooting: the
Live home directory normally resides in RAM.

The optional `--with-offline-repo` remains separate. Included programs already
work offline; the extra repository is for installing selected XBPS packages.

## Acceptance checks on a disposable VM

Use scratch virtual disks and sample files; do not attach production disks.

1. Boot the ISO through BIOS and UEFI. Confirm one Rescue Center opens and the
   regular desktop, menu, network and terminal work. Disable the startup option,
   log out/in, and confirm it is honored within the session's persistent state.
2. Confirm the graphical storage tools and terminal recovery programs open.
   Test search/categories and the offline guide without network access.
3. Attach a scratch disk with a filesystem and confirm it is not automounted.
   Check it while unmounted, then mount it and confirm the center refuses the
   check. Exercise a mapped LUKS/LVM volume and mounted-child refusal too.
4. Save a report to another mounted disk, including a path with spaces. Check
   its contents and permissions; an existing filename must not be overwritten.
5. Image a scratch disk with ddrescue to a separate disk, interrupt and resume
   with the same mapfile. Verify the image and recover sample files from a copy.
6. Create and restore a backup onto another disposable target with FSArchiver
   or Partclone; compare recovered sample-file checksums.
7. Test SMB/NFS/SSH transfer destinations. Confirm SSH does not listen until
   deliberately enabled, and stop it after the test.
8. Exercise the boot-repair checklist on a disposable installed guest matching
   each intended firmware mode. Use the guest distribution's own repair tools.

Automated tests and dependency dry-runs do not replace these boot and storage
tests. A host-only package calculation is not a measurement of compressed ISO
size.

## Upstream references

- [GNU ddrescue manual](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
- [TestDisk](https://www.cgsecurity.org/wiki/TestDisk)
- [FSArchiver quick start](https://www.fsarchiver.org/quickstart/)
- [Partclone usage](https://partclone.org/usage/)